/*
* ============================================================================
*  Name        : ccamautofocus.h
*  Part of     : Symbian/S60 Camera Wrapper
*  Description : Class for controlling the autofocus (optimised AF) of the
*                onboard camera on S60 3rd Edition (3.0, 3.1) devices
*  Version     : 
*
* This program is free software. It comes without any warranty, to
* the extent permitted by applicable law. You can redistribute it
* and/or modify it under the terms of the Do What The Fuck You Want
* To Public License, Version 2, as published by Sam Hocevar. See
* http://sam.zoy.org/wtfpl/COPYING for more details.
*
* You are welcome to, but not required to, contribute any modifications that
* improve stability, usability and/or feature set of the library back to
* Symbian/S60 Camera Wrapper project, as long as binary compatibility is
* retained. See https://projects.forum.nokia.com/camerawrapper for more info.
* ============================================================================
*/

#ifndef CCAMAUTOFOCUS_H
#define CCAMAUTOFOCUS_H

//  INCLUDES
#include <e32base.h>

// DATA TYPES

// FORWARD DECLARATIONS
class CCamAutoFocusImpl;
class CCamera;

// CLASS DECLARATIONS

/**
*  MCamAutoFocusObserver -- Callback interface that AF client must implement
*/
class MCamAutoFocusObserver
    {

public: 
        /**
        * Delivers notification of completion of auto focus initialisation to 
        * an interested party.
        * @param aError Reason for completion of focus request.
        */
        virtual void InitComplete( TInt aError ) = 0;

        /**
        * Delivers notification of completion of an optimised focus request to
        * an interested party.
        * @param aError Reason for completion of optimised focus request.
        */
        virtual void OptimisedFocusComplete( TInt aError ) = 0;
    };
    

/**
*  CCamAutoFocus -- class that can be used to control autofocus of the camera
*  @since 3.0
*  @lib camautofocus.lib
*/
class CCamAutoFocus : public CBase
    {
    public:
    
        enum TAutoFocusRange
        {
        /** Macro mode - for close up shots */
        ERangeMacro    = 0x0001,

        /** Portrait focus range - optimised focus range for taking portrait style shots */
        ERangePortrait = 0x0002,

        /** Normal focus range - used in most shots */
        ERangeNormal   = 0x0004,

        /** Infinite focus range - used typically for outdoor landscape shots */
        ERangeInfinite = 0x0008
        };
        
        /**
        * Symbian C++ two-phased constructor.
        * @param aCamera pointer to CCamera object that supports autofocus
        * @leave Leaves with KErrNotSupported if camera does not support AF
        * @leave May also leave with other system-wide error code.
        */
        IMPORT_C static CCamAutoFocus* CCamAutoFocus::NewL(CCamera* aCamera);
        
        /**
        * Destructor.
        */
        IMPORT_C ~CCamAutoFocus();

    public:
    
        /**
        * Asynchronous camera initialisation method in which AF parameters are
        * set to default values. On completion, InitComplete() of the observer 
        * is called. Caller must set itself as the observer of this API.
        * This method will leave if the API cannot be initialised correctly.
        * @leave Leaves with KErrInUse if camera is not reserved
        * @leave Leaves with KErrNotReady if camera power is not on
        */
        IMPORT_C void InitL( MCamAutoFocusObserver& aObserver );
        
        /**
        * Asynchronous request to achieve optimised focus lock.
        * @leave Leaves with KErrNotSupported if optimised focussing not 
        *        supported by device
        * @leave Leaves with KErrInUse if camera is not reserved or async
        *        operation is pending
        * @leave Leaves with KErrNotReady if camera power is not on or 
        *        InitL not called
        */
        IMPORT_C void AttemptOptimisedFocusL();
        
        /**
        * Select the focus range to use during AF operations.
        * This method will leave if the requested range is unsupported, or other error conditions.
        * @param aAFRange The requested AF range.
        * @leave Leaves with KErrInUse if camera is not reserved or async operation is pending
        * @leave Leaves with KErrNotReady if camera power is not on or InitL not called
        */
        IMPORT_C void SetFocusRangeL( TAutoFocusRange aAFRange = ERangeNormal );
        
        /**
        * return the current focus range.
        * @param aAFRange On return, contains the AF range.
        */
        IMPORT_C void FocusRange( TAutoFocusRange& aAFRange );

        /**
        * Single cancel method that will cancel the current asynchronous 
        * request, if one is outstanding at the current time.
        * Can be called safely even if no outstanding request exists.
        * Single method can be used to cancel either the InitL or 
        * AttemptOptimisedFocusL requests.
        * IMPORTANT: Only call this method BEFORE releasing the camera, not 
        *            after.
        * Cancelling optimised focus attempt locks focus to where it is when
        * cancelling.
        * ResetToIdleL should be called to return lenses to default position.
        */
        IMPORT_C void Cancel();

        /**
        * Synchronously bring the AF subsystem to idle.
        * This method is provided to allow the AF subsystem to be brought to a
        * low-power state following completion of a capture operation.
        * Use of this method is not mandatory from a logical point of view, but
        * is desirable from a power management perspective.
        * Any outstanding async requests should be cancelled before calling this
        * method.
        * @leave Leaves with KErrInUse if camera is not reserved or async
        *        operation is pending
        * @leave Leaves with KErrNotReady if camera power is not on or InitL
        *        not called
        */
        IMPORT_C void ResetToIdleL();

        /**
        * This method is provided to allow the AF subsystem & API to be shutdown
        * in a controlled way.
        * Any outstanding asynchronous requests will be cancelled, and all HW & 
        * SW resources consumed or managed by the API will be released.
        * After calling this method, the client must call InitL before 
        * attempting to perform any new focusing operations.
        * IMPORTANT: Only call this method BEFORE releasing the camera, not 
        * after.
        */
        IMPORT_C void Close();
        
    private:
    
    	/**
        * C++ default constructor. [private]
        */
        CCamAutoFocus();
        
      /**
      * Symbian C++ second phase constructor [private]
      */
        void ConstructL(CCamera* aCamera);
      
    private:	// data
    
        CCamAutoFocusImpl* iImpl;
		};

#endif      // CCAMAUTOFOCUS_H   
            
// End of File
